# Wi-Fi/BT

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**Quectel Pi** Debian development board supports **Wi-Fi** and **Bluetooth (BT)** connectivity. This document is based on the current on-board environment: the operating system is Debian GNU/Linux 13 (trixie), the wireless network interface is `wlan0`, the NetworkManager service is active, and commands such as `nmcli`, `wpa_cli`, `wpa_supplicant` and `bluetoothctl` are available on the board.

> 💡 It is recommended to use the Debian desktop or `nmcli` to connect to Wi-Fi. Use `wpa_cli` / `wpa_supplicant` only when NetworkManager is unavailable or when low-level debugging or verification of wpa_supplicant behavior is required.

# Using the Wi-Fi Function

## Method 1: Connect to Wi-Fi from the Debian Desktop

If a MIPI/HDMI display is connected and the Debian GNOME desktop is open, you can connect to a wireless network directly from the desktop network menu. This method is suitable for general functional verification and does not require commands to be entered manually.

1. Connect a display, mouse, and keyboard, power on the development board, and enter the Debian desktop.

2. Click the system status area in the upper-right corner of the desktop to expand the network menu.

3. Ensure that the Wi-Fi switch is on. If it is off, enable Wi-Fi first.

4. Select the target SSID from the wireless network list.

5. Enter the Wi-Fi password and confirm the connection.

6. After the connection is established, access a web page in a browser, or run `ip addr show wlan0`, `ping -c 4 8.8.8.8` in the terminal to verify network connectivity.

## Method 2: Connect to Wi-Fi Using nmcli (Recommended Command-Line Method)

`nmcli` is the NetworkManager command-line tool. NetworkManager is currently running on the Debian board, and `wlan0` is recognized as a Wi-Fi device. Therefore, this method is recommended for establishing a connection from the command line.

**1. Check the Wireless Device Status**

```bash
nmcli general status
nmcli radio wifi
nmcli device status
```

Under normal conditions, `wlan0` should be shown with the type `wifi`. If Wi-Fi is shown as disabled, run:

```bash
nmcli radio wifi on
```

**2. Scan for Nearby Wi-Fi Networks**

```bash
nmcli device wifi rescan ifname wlan0
nmcli device wifi list ifname wlan0
```

**3. Connect to the Target Wi-Fi Network**

```bash
nmcli device wifi connect "SSID_NAME" password "Wi-Fi_PASSWORD" ifname wlan0
```

If the SSID or password contains spaces or special characters, it is recommended to retain the double quotation marks. After the connection is established, NetworkManager automatically saves the connection profile and will usually reconnect automatically after subsequent startups or when network service is restored.

**4. Check the Connection Result**

```bash
nmcli connection show --active
ip addr show wlan0
ip route
ping -c 4 8.8.8.8
```

**5. Common Maintenance Commands**

```bash
# Disconnect the current wlan0 connection
nmcli device disconnect wlan0

# Bring up the saved connection again
nmcli connection up "SSID_NAME"

# Delete the saved connection
nmcli connection delete "SSID_NAME"
```

## Method 3: Connect to Wi-Fi Using wpa_cli / wpa_supplicant (Low-Level Debugging Method)

`wpa_supplicant` is the low-level Linux component responsible for Wi-Fi authentication and connection, and `wpa_cli` is its interactive control tool. This method is suitable when NetworkManager is not managing the device and the driver, firmware, or authentication process must be verified. If `wlan0` is currently managed by NetworkManager, disconnect it or stop NetworkManager first to prevent two processes from controlling the same wireless network adapter simultaneously.

> 💡 Before using the wpa_supplicant method, ensure that it will not affect the current remote connection. If the development board relies on Wi-Fi for remote login, stopping NetworkManager may interrupt the network connection.

**1. Stop NetworkManager from Managing wlan0 (As Needed)**

```bash
nmcli device disconnect wlan0
# Alternatively, temporarily stop NetworkManager during debugging
systemctl stop NetworkManager
```

**2. Create the wpa_supplicant Configuration File**

```bash
wpa_passphrase "SSID_NAME" "Wi-Fi_PASSWORD" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
```

**3. Start wpa_supplicant**

```bash
ip link set wlan0 up
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
```

**4. Obtain an IP Address Through DHCP**

```bash
dhclient wlan0
# If dhclient is not installed, use udhcpc or NetworkManager to obtain an address as appropriate for the system
```

**5. Check the Connection Status Using wpa_cli**

```bash
wpa_cli -i wlan0 status
wpa_cli -i wlan0 scan
wpa_cli -i wlan0 scan_results
```

When `wpa_state=COMPLETED` and `ip_address` contains a valid address, Wi-Fi authentication and IP address acquisition are functioning properly.

**6. Connect Interactively Using wpa_cli (Optional)**

```bash
wpa_cli -i wlan0
> scan
> scan_results
> add_network
> set_network 0 ssid "\"SSID_NAME\""
> set_network 0 psk "\"Wi-Fi_PASSWORD\""
> enable_network 0
> save_config
> status
```

# Using the Bluetooth Function

**Quectel Pi** Debian development board has built-in Bluetooth functionality. The on-board `bluetooth` service is currently active, and `bluetoothctl show` can detect the controller, indicating that the basic Bluetooth service has started.

## Method 1: Connect to a Bluetooth Device from the Debian Desktop

1. After entering the Debian desktop, open Settings.

2. Open the Bluetooth page.

3. Turn on Bluetooth and set the target Bluetooth device to pairing/discoverable mode.

4. Select the target device from the device list, such as a Bluetooth headset, keyboard, or mouse.

5. Follow the on-screen prompts to complete Pair and Connect.

## Method 2: Connect to a Bluetooth Device Using bluetoothctl

If no graphical interface is available, or debugging through ADB or a serial port is required, use `bluetoothctl`.

```bash
systemctl status bluetooth
bluetoothctl
```

After entering `bluetoothctl`, run:

```
power on
agent on
default-agent
scan on
```

After the target device is discovered, record its MAC address, and then run:

```
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit
```

After connecting, use the following commands to check the controller and device status:

```bash
bluetoothctl show
bluetoothctl devices
bluetoothctl info XX:XX:XX:XX:XX:XX
```

# Troubleshooting

| **Symptom** | **Troubleshooting Method** |
| --- | --- |
| No Wi-Fi Networks Are Found | Check the antenna connection, run `rfkill list` to check whether Wi-Fi is soft-blocked or hard-blocked, run `nmcli radio wifi on`, and then scan again. |
| wlan0 Does Not Exist | Run `ip link`, `dmesg \| grep -i wlan` to check whether the driver and firmware are loaded. |
| nmcli Connection Fails | Check whether the SSID and password are correct, and use `journalctl -u NetworkManager -b` to view the NetworkManager logs. |
| wpa_cli Indicates That It Cannot Connect | Ensure that wpa_supplicant has started and that its control interface matches the interface used by `wpa_cli -i wlan0`. |
| Bluetooth Cannot Discover Devices | Ensure that `systemctl status bluetooth` is functioning properly, run `bluetoothctl power on`, and ensure that the peripheral is in discoverable mode. |

# On-Board Verification Commands

During maintenance or troubleshooting, first collect the following information to verify the system, interface, and service status:

```bash
cat /etc/os-release
uname -a
ip link show wlan0
nmcli general status
nmcli device status
systemctl is-active NetworkManager
systemctl is-active bluetooth
bluetoothctl show
```